=begin pod :tag<list>

=TITLE Glossary

=SUBTITLE Glossary of Perl 6 terminology

=head1 Abstract Class
X<|Abstract Class>

The generic Computer Science term "abstract class" defines the
L<interface|#Interface> or L<#API> of a class.  In Perl 6, this is
implemented using L<roles|#Roles> with
L<stubbed|#Stub> methods.

    role Canine {
        method bark { ... }          # the ... indicates a stub
    }

    class Dog does Canine {
        method bark { say "woof" }   # *MUST* be implemented by class
    }

=head1 Advent Calendar
X<|Advent Calendar>

In the context of Perl 6, a yearly set of blog posts for each day from
the 1st until the 25th of December, to be found at
L<https://perl6advent.wordpress.com>.

=head1 Adverb
X<|Adverb>

Generically, an adverb is a named argument to a function.  There are also
some specific syntax forms that allow adverbs to be tucked into some
convenient places:

    q:w"foo bar";   # ":w" is a Quotelike form modifier adverb
    m:g/a|b|c/;     # ":g" is also
=comment TODO: Add this back in when :rotate on infix operators is supported
=comment 4 +> 5 :rotate # ":rotate" is an operator adverb
    @h{3}:exists;   # ":exists" is also, but is known as a subscript adverb

Adverbs are usually expressed with colon pair notation, and for this
reason colon pair notation is also known as the adverbial pair form:

    :a(4)          # Same as "a" => 4

Some other forms that use a colon in ways that have adverb-like semantics
are called adverbial forms.  One special form starts with an integer value,
followed by a name (for the key):

    :20seconds     # same as seconds => 20

Also see L<#Colon Pair and Colon List>.

=head1 Adverbial Pair
X<|Adverbial Pair>

A generalized form of C<pair notation>.  They all start with the colon, like:

=begin table
  adverbial pair  | pair notation
  ================|==============
    :foo<bar>     | foo => 'bar'
    :foo(42)      | foo => 42
    :42foo        | foo => 42
    :$foo         | foo => $foo
    :foo          | foo => True
    :!foo         | foo => False
=end table

Also see L<#Adverb> and L<#Colon Pair and Colon List>.

=head1 Allomorph
X<|Allomorph>

A type that has two related values which may be used depending on the
context. For example L<IntStr|/type/IntStr> allomorph C<is> both
an L<Int|/type/Int> and a L<Str|/type/Str>, so it will be accepted by
anything that expects an C<Int>, a C<Str>, or an C<IntStr>. Keep in mind
that certain constructs, such as L<sets, bags, and mixes|/language/setbagmix>
care about object identity, and so will not accept an allomorph as equivalent
of its components alone.

The I<allomorph> types L<IntStr|/type/IntStr>, L<NumStr|/type/NumStr>,
L<RatStr|/type/RatStr> and L<ComplexStr|/type/ComplexStr> may be created
as a result of parsing a quoted string:

    say <42>.^name;     # OUTPUT: «IntStr␤»
    say <42.1e0>.^name; # OUTPUT: «NumStr␤»
    say <42.1>.^name;   # OUTPUT: «RatStr␤»

Note: angle brackets can also be used to create literals for which you'd
normally need to use some operator (e.g. C</> for L<Rat> or C<+> for
L<Complex>). This allows you to use such literals in places where
expressions are not allowed, for example, as literals in signatures:

=for code :skip-test
    # Wrong, can't use an operator there:
    multi foo (1/3) { say "It's one third!" }
=for code
    # Right, a Rat literal:
    multi foo (<1/3>) { say "It's one third!" }

If you I<do> want an allomorph and not a literal L<Numeric>,
then include whitespace around angle brackets:

    say <42/1>.^name;    # OUTPUT: «Rat␤»
    say <42+0i>.^name;   # OUTPUT: «Complex␤»
    say < 42+0i >.^name; # OUTPUT: «ComplexStr␤»
    say < 42/1 >.^name;  # OUTPUT: «RatStr␤»

=head1 Anonymous
X<|Anonymous>

A subroutine, method or submethod is called I<anonymous> if it can't be
called by name.

    # named subroutine
    sub double($x) { 2 * $x };

    # anonymous subroutine, stored in a named scalar
    my $double = sub ($x) { 2 * $x };

Note that it is still allowed to have a name, but you cannot call it by
that name:

    =for code
    # anonymous, but knows its own name
    my $s = anon sub triple($x) { 3 * $x }
    say $s.name;        # OUTPUT: «triple␤»
    =for code :skip-test
    say triple(42);     # OUTPUT: «Undeclared routine: triple␤»

=head1 API
X<|API>

Application Programming Interface. Ideally, someone using your system or
library should be able to do so with knowledge only of the API, but not
necessarily knowing anything about the internals or implementation.

See also L<#Abstract Class>.

=head1 Apocalypse
X<|Apocalypse>

A document originally written by L<#TimToady>, in which he processed the
initial barrage of RFCs that came out of the Perl community.  Now only kept
as an historical document for reference.  See also L<#Exegesis> and
L<#Synopsis>.

=head1 Arity
X<|Arity>

The number of L<positional|/type/Positional> operands expected by an
L<operator|#Operator>, subroutine, method or callable block.

    =begin code :preamble<class Foo {};>
    sub infix:<+>(Foo $a, Foo $b) { $a.Int + $b.Int }  # arity of "+" is 2
    sub frobnicate($x) { ... }                         # arity of 1
    sub the-answer() { 42 }                            # arity of 0
    -> $key, $value { ... }                            # arity of 2
    =end code

The arity of a C<Callable> is one of the main selectors in
L<multi-dispatch|#Multi-Dispatch>.

=head1 Autothreading
X<|Autothreading>

Autothreading is what happens if you pass a L<Junction|/type/Junction> to
a subroutine that expects a parameter of type L<Any|/type/Any> or a subtype thereof
(such as anything L<Cool|/type/Cool>). The call is then executed for each
value of the junction. The result of these calls is assembled in a new
junction of the same type as the original junction.

    sub f($x) { 2 * $x };
    say f(1|2|3) == 4;    # OUTPUT: «any(False, True, False)␤»

Here C<f()> is a sub with one parameter, and since it has no explicit type,
it is implicitly typed as C<Any>.  The C<Junction> argument causes the
C<f(1|2|3)> call to be internally executed as C<f(1)|f(2)|f(3)>, and the
resulting junction is C<2|4|6>.  These are then all compared to C<4>,
resulting in a junction C<False|True|False>.  This process of separating
junction arguments into multiple calls to a function is called
I<autothreading>.

If you use the resulting junction in a boolean context, such as with an
C<if>, it collapses into a single boolean which is C<True> if any of the
values in the junction are True.

    =for code :preamble<sub f {};>
    if f(1|2|3) == 4 {    # fires because f(2) == 4 is true
        say 'success';
    }


=head1 Backtracking
X<|Backtracking>

Backtracking is the default way a regexp is matched. The engine
is allowed to explore several ways moving backward in the string
characters in order to allow every piece of a regexp
to match something.
For more information see L<Regexp Backtracking section|/language/regexes#backtracking>.

=head1 binder

When you pass an argument list to a function (or any other callable, like a
method or a block), the argument list gets bound to the parameters in the
signature. The code that does this is called the I<binder>.

=head1 block
X<|block>

=head1 bytecode
X<|bytecode>

=head1 Camelia
X<|Camelia>

A butterfly image intended primarily to represent Perl 6, The Language.

=head1 Colon Pair and Colon List
X<|Colon Pair> X<|Colon List>

A colon pair is a shorthand syntax used to create or visually present
a L<Pair|/type/Pair> object.  The two most common forms are:

    :a(4)          # Same as "a" => 4,   same as Pair.new("a", 4)
    :a<4>          # Same as "a" => "4", same as Pair.new("a", "4")

This is also known as the adverbial pair form.  Note: when the part after
the colon and before the brackets is not a legal identifier, other
semantics apply, not all of which produce Pair objects.

Two other common forms are:

    :a             # Same as :a(True)
    :!a            # Same as :a(False)

A colon list just means that a list that contains only colon pairs,
does not need commas, or even spaces:

    :a(4):c:!d:c   # Same as a => 4, c => True, d => False, c => True

Finally, if there is a variable with the same name as an intended adverbial
pair, you don't have to specify the name twice, but just specify the adverb
with the appropriate sigil:

    =begin code :skip-test
    :$foo          # same as foo => $foo
    :@bar          # same as bar => @bar
    :%mapper       # same as mapper => %mapper
    :&test         # same as test => &test
    =end code

See also L<#Adverb>.

=head1 Community
X<Community>

See L<https://perl6.org/community/> for information about how to participate
in the friendly Perl 6 community.

=head1 Damian Conway

Original author of the L<#Exegesis> (among many other things).
See also L<https://en.wikipedia.org/wiki/Damian_Conway>.

=head1 diffy
X<|diffy>

See L<operator|#Operator>. It means the type of the operator result is
sufficiently different from its arguments that op= makes little sense

=head1 Exegesis
X<|Exegesis>

A document originally written by L<#TheDamian>, in which he tried to explain
the L<Apocalypses|#Apocalypse> to the common (wo)man.  Now only kept as an
historical document for reference.  See also L<#Synopsis>.

=head1 fiddly
X<|fiddly>

Too complicated to apply a meta-op to. See L<operator|#Operator>.

=head1 Huffmanize

With reference to L<Huffman coding|https://en.wikipedia.org/wiki/Huffman_coding>,
"huffmanizing" is making things that are commonly used easier, and often shorter,
to type. With things that are used less frequently it's both less of a bother
to type longer pieces of code and often longer, more descriptive naming
is necessary to easily be reminded of what the rarely-used feature does.

For example, printing output is a common task, while performing
thread-safe atomic addition on native atomicity-safe integers is much less so.
There's a need to "huffmanize" the task printing and that's why you can do it by
just typing three letters L<put>. But there's no need to "huffmanize" the
rarely-needed atomic operators, which is why you type the lengthier
names, such as L<atomic-inc-fetch>. L<put> is a bit of a vague name, but because
it's commonly used, it's easy to learn what it does. L<atomic-inc-fetch>,
on the other hand is rarer, and the more descriptive name helps recall
its purpose better.

=head1 iffy
X<|iffy>

Often used as a boolean value. See L<operator|#Operator>.


=head1 Instance
X<|instance>

An I<instance> of a class is also called an I<object> in some other
programming languages. It has storage for attributes and is often the return
value of a call to a method called C<new>, or a literal.

Instances of most types are defined to be C<True> e.g.,
C<defined($instance)> is C<True>.

    my Str $str = "hello";  ## this is with builtin types, e.g. Str
    if defined($str) {
        say "Oh, yeah. I'm defined.";
    }
    else {
        say "No. Something off? ";
    }

    ## if you wanted objects...
    class A {
        # nothing here for now.
    }

    my $an_instance = A.new;
    say $an_instance.defined.perl;# defined($an_instance) works too.

To put things another way, a class contains the blueprints of methods and
attributes, and an instance carries it into the real world.

=head1 Interface
X<|Interface>

An interface is an L<abstract class|#Abstract Class>.

=head1 IRC
X<|IRC>

Internet Relay Chat.  Perl 6 developers and users usually hang out on the
C<#perl6> channel of C<irc.freenode.org>. Currently available bots are:

=head2 camelia
X<|camelia>

The L<#Bot> on the #perl6 L<#IRC> channel that evaluates code, e.g.:

    =begin code :lang<text>
    [16:28:27]  <lizmat>  m: say "Hello world"
    [16:28:28]  <+camelia>    rakudo-moar 812a48: OUTPUT«Hello world␤»
    =end code

This is a handy tool for showing people if the output is (un)expected.

=head2 dalek
X<|dalek>

The L<#Bot> on the #perl6 L<#IRC> channel that reports changes made to
various Perl 6 related L<repositories|#Repository>.

    =begin code :lang<text>
    [15:46:40] <+dalek> doc: 2819f25 | lizmat++ | doc/Language/glossary.pod:
    [15:46:40] <+dalek> doc: Add stubs for stuff inside the glossary already
    [15:46:40] <+dalek> doc: review: https://github.com/perl6/doc/commit/2819f250
    =end code

=head2 yoleaux
X<|yoleaux>

The L<#Bot> on the #perl6 L<#IRC> channel that provides various services
to people logged in.  Commands to yoleaux (a pun on YOLO) start with a period.
Some often used commands are:

=head3 .tell

Leave a message to another user who is currently not logged in.  The message
will be relayed as soon as the user says anything on the channel.

    =begin code :lang<text>
    .tell lizmat I've read the glossary
    =end code

=head3 .u

Look up unicode codepoint information from either a codepoint, or the name
of a codepoint.

    =begin code :lang<text>
    [16:35:44]  <lizmat>   .u empty set
    [16:35:45]  <yoleaux>  U+2205 EMPTY SET [Sm] (∅)
    [16:36:29]  <lizmat>   .u ∅
    [16:36:30]  <yoleaux>  U+2205 EMPTY SET [Sm] (∅)
    =end code

Some L<#IRC> clients then easily allow you to copy/paste the codepoint in
question, which can be sometimes be easier than other unicode codepoint
input methods.

=head1 IRC Lingo

The following terms are often used on the Perl 6 related L<#IRC> channels:

=head2 ALAP
X<|ALAP>

As Late As Possible

=head2 autopun
X<|autopun>

A self-referencing pun, e.g. "Are you ignorant or apathetic?" - "I don't
know, and I don't care."

=head2 backlog
X<|backlog>

That part of a discussion on an L<#IRC> channel that you've missed.  If it
is not or no longer available in your IRC client, you can go to sites such
as L<http://irc.perl6.org> to see what has been logged for you.

=head2 Bot
X<|Bot>

A program that does automatic tasks on one or more L<#IRC> channels by
acting like a regular user (as far as the IRC server is concerned) and
performing some tasks that may involve answering to users requests.
Examples are L<#camelia>, L<#dalek> and L<#yoleaux>.

=head2 DWIM
X<|DWIM>

Do What I Mean.  A programming language designer motto.

=head2 flap
X<|flap>

Sometimes a test will fail under some conditions, but not others; when this
test passes some test runs and fails others, it's called flapping.

=head2 fossil
X<|fossil>

Something in a generally current document that is no longer true but which
has not yet been fixed by correcting or removing it.

=head2 FSVO
X<|FSVO>

For Some Value Of...

=head2 FTFY
X<|FTFY>

Fixed That For You

=head2 IIRC
X<|IIRC>

If I Read (or Remember) Correctly

=head2 IMHO
X<|IMHO>

In My Humble Opinion

=head2 IWBN
X<|IWBN>

It Would Be Nice

=head2 LHF
X<|LHF>

Low Hanging Fruit.  Usually used in the context of a (relatively) simple
task to be performed by a (relative) newbie.

=head2 LGTM
X<|LGTM>

Looks Good To Me

=head2 LTA
X<|LTA>

Less Than Awesome.  Usually used in the context of an error message that
is rather non-descriptive or unrelated to the actual error.

=head2 NST
X<|NST>

No Such Thing

=head2 Opt
X<|Opt>

Short for "optimization", usually in either the context of L<spesh|#Spesh> or
JIT.

=head2 PB
X<|PB>

Short for "problem".  As in "that's not the pb".

=head2 PR
X<|PR>

See L<#Pull Request>.

=head2 P5
X<|P5>

Perl 5

=head2 P6
X<|P6>

Perl 6

=head2 RSN
X<|RSN>

Real Soon Now

=head2 RT
X<|RT>

Request Tracker (L<http://rt.perl.org/>).  The place where all the bugs
related to L<#Rakudo> live.

=head2 TIMTOWTDI
X<|TIMTOWTDI>

An alternative form of L<#TMTOWTDI>, explicitly including the "is" from
the contraction "There's".

=head2 TMI
X<|TMI>

Too Much Information.

=head2 TMTOWTDI
X<|TMTOWTDI>

"There's More Than One Way To Do It", the Perl motto.

=head2 UGT
X<|UGT>

"Universal Greeting Time" - i.e., it's always "morning".

=head2 WFM
X<|WFM>

Works For Me

=head2 WIP
X<|WIP>

Work In Progress

=head2 WP
X<|WP>

Wikipedia

=head2 WW
X<|WW>

Short for C<wrong window>.  When on L<#IRC>, someone types something in a
channel that was intended for another channel, or for a private message.

=head1 Larry Wall

L<Perl's|#Perl> benevolent dictator for life, among many other things.  See
also L<https://en.wikipedia.org/wiki/Larry_Wall>.

=head1 Lexing
X<|Lexing>

=head1 Literal
X<|Literal>

A I<literal> is a piece of code that directly stands for an (often built-in)
object and also refers to the object itself.

    my $x = 2;      # the 2 is a literal
    say $x;         # $x is not a literal, but a variable
    my $s = "Foo";  # the "Foo" is a literal, the $s is a variable

=head1 lvalue
X<|Value>

An I<lvalue>, or a I<left value>, is anything that can appear on the left
hand side of the assignment operator C<=>.  It is anything you can assign
to.

Typical lvalues are variables, private and C<is rw> attributes, lists of
variables and lvalue subroutines.

Examples of lvalues:

=begin table
    Declaration             lvalue          Comments

    my $x;                  $x
    my ($a, $b);            ($a, $b)
    has $!attribute;        $!attribute     Only inside classes
    has $.attrib is rw;     $.attrib
    sub a is rw { $x };     a()
=end table

Examples of things that are not lvalues:

=begin table
    3                        literals
    constant x = 3;          constants
    has $.attrib;            attributes; you can only assign to $!attrib
    sub f { }; f();          "normal" subs are not writable
    sub f($x) { $x = 3 };    error - parameters are read-only by default
=end table

These are typically called L<rvalues|#rvalue>.

=head1 Mainline
X<|Mainline>

The C<mainline> is the program text that is not part of any kind of block.

    use v6.c;     # mainline
    sub f {
                  # not in mainline, in sub f
    }
    f();          # in mainline again

You can also have the mainline of any package-like declarator, such as
class, L<module|/language/modules>, L<grammar|/language/grammars>, etc.  These are
typically run just after the class/module/grammar have been compiled (or
when loaded from a pre-compiled file).

=head1 MoarVM
X<|MoarVM>

MoarVM is short for Metamodel On A Runtime Virtual Machine.
It's a virtual machine designed specifically for L<#NQP> and its L<MOP|/language/mop>:
L<#6model>.  A document about
L<the purpose of MoarVM|https://github.com/MoarVM/MoarVM/blob/master/docs/reveal.md>.
MoarVM has some similarities with the Hotspot VM so you may peruse its
L<glossary|http://openjdk.java.net/groups/hotspot/docs/HotSpotGlossary.html>
for entries missing from the present one.

=head1 Multi-Dispatch
X<|Multi-Dispatch>X<|MMD>

The process of picking a candidate for calling of a set of L<methods|/type/Method> or L<subs|/type/Sub> that
come by the same name but with different arguments. The most narrow candidate
wins. In case of an ambiguity, a routine with C<is default> trait will be
chosen if one exists, otherwise an exception is thrown.

=head1 multi-method
X<|multi-method>

A L<method|/type/Method> that has multiple candidates going by the same name
and are subject to L<Multi-Dispatch|#Multi-Dispatch>.

=head1 NFG
X<|NFG>

Normal Form Grapheme

=head1 Niecza
X<|Niecza>

An implementation of Perl 6 targeting the .NET platform.  No longer actively
maintained.

=head1 Not Quite Perl
X<|NQP>

See L<#NQP>.

=head1 NQP
X<|Not Quite Perl>

NQP is a primitive language for writing subroutines and methods using a
subset of the Perl 6 syntax.  It's not intended to be a full-fledged
programming language, nor does it provide a runtime environment beyond
the basic VM primitives.  Compilers (such as L<#Rakudo> typically use
NQP to compile action methods that convert a parse tree
into its equivalent abstract syntax tree representation.

=head1 NYI
X<|NYI>

Not Yet Implemented

=head1 opcode
X<|opcode>

=head1 Operator
X<|Operator>

An expression is made of operators and operands. More precisely it is made
of an operator and operands that can be subexpressions or L<#value>s.
Operators are an alternative syntax for a L<#multi-method>. With that
syntax, what would be the arguments of the function are named
operands instead. Operators are classified into
L<categories|https://design.perl6.org/S02.html#Grammatical_Categories> of
categories.  A category has a precedence, an arity, and can be L<#fiddly>,
L<#iffy>, L<#diffy>.  Perl 6 is very creative as to what is an operator, so
there are many categories.  Operators are made of many tokens, possibly with
a subexpression.  For example, C<@a[0]> belongs to the postcircumfix
category, is broken into the operand C<@a> and the postcircumfix operator
C<[0]> where C<0> is the postcircumfixed subexpression.

The C<< <O(I<...>)>  >> construction gives information about an operator
that completes the information provided by its category.  Below
C<%conditional> is the category, C<< :reducecheck<ternary> >>, which
specifies calling C<.ternary> to post-process the L<parse subtree|#Parse Tree>
and C<< :pasttype<if> >> specifies the NQP L<#opcode> generated in the
AST from the parse subtree.

        <O('%conditional, :reducecheck<ternary>, :pasttype<if>')>


=head1 Parse Tree
X<|Parse Tree>

=head1 Parameter
X<|Parameter>

L<Parameter|/type/Parameter> is a class to define parameters to
subroutines, method and a L<callable blocks|/type/Callable>.
As opposed to the arguments you specify when calling a
subroutine/method/callable block.

    sub foo($bar) { say $bar }     # $bar is a parameter
    foo(42);                       # 42 is an argument

=head1 Parrot
X<|Parrot>

A L<virtual machine|#Virtual Machine> designed to run Perl 6 and other
dynamic languages.  No longer actively maintained.

=head1 PAST
X<|PAST>

L<#Parrot> AST.

=head1 Perl
X<|Perl>

The Perl programming language in its many forms.

=head1 PERL
X<|PERL>

A way to describe L<Perl|#Perl> as a language, considered to be improper by
many in the L<Perl Community|/language/community>.

=head1 POD
X<|POD>

B<P>lain B<O>l' B<D>ocumentation, a documentation format understood by Perl
6. See L<S26|https://design.perl6.org/S26.html> for details.

=head1 Pull Request
X<|Pull Request>

A feature of L<https://github.com> that allows you to make patches
to be easily applied using the Github user interface. It means you
request someone to do a git pull from your L<repository|#Repository> to hers. In
GitHub, it can be done automatically through the web  interface. PR is
its usual acronym.

=head1 pugs
X<|pugs>

L<pugs|https://en.wikipedia.org/wiki/Pugs> was one of the first interpreters/compilers written for Perl 6. It was written in Haskell by Audrey Tang.

=head1 QAST
X<|QAST>

Successor to L<#PAST> ('Q' being the next letter after 'P').

=head1 Rakudo
X<|Rakudo>

Rakudo is the name of a Perl 6 implementation that runs on L<#MoarVM> and
the JVM.  It is an abbreviation of C<Rakuda-do>, which, when translated
from Japanese, means "The Way of the Camel".  Also, in Japanese, "Rakudo"
means "Paradise."

=head1 Reify
X<|Reify>

In English language, L<reify means|http://www.dictionary.com/browse/reify> to
"to convert into or regard as a concrete thing." Its meaning in Perl 6 is very
similar, in that conceptual things, like "elements of an infinite list" get
I<reified> when you try to operate on some of them:

    # A list containing infinite number of un-reified Fibonacci numbers:
    my @fibonacci = 1, 1, * + * … ∞;

    # We reify 10 of them, looking up the first 10 of them with array index:
    say @fibonacci[^10]; # OUTPUT: «(1 1 2 3 5 8 13 21 34 55)␤»

    # We reify 5 more: 10 we already reified on previous line, and we need to
    # reify 5 more to get the 15th element at index 14. Even though we need only
    # the 15th element, the original Seq still has to reify all previous elements:
    say @fibonacci[14]; # OUTPUT: «987␤»

Above we were reifying a L<Seq> we created with the
L<sequence operator|/language/operators#index-entry-%E2%80%A6_operators>, but
other things use the concept as well. For example, an un-reified L<Range> is just
the two end points. In some languages, calculating the sum of a huge range is a
lengthy and memory-consuming process, but Perl 6 calculates it instantly:

    say sum 1 ..9_999_999_999_999; # OUTPUT: «49999999999995000000000000␤»

Why? Because the sum can be calculated I<without> reifying the Range; that is
without figuring out all the elements it contains. This is why this feature
exists. You can even make your own things you can reify-on-demand, using
L«C<gather> and C<take>|/syntax/gather%20take»:

    my $seq = gather {
        say "About to make 1st element"; take 1;
        say "About to make 2nd element"; take 2;
    }
    say "Let's reify an element!";
    say $seq[0];
    say "Let's reify more!";
    say $seq[1];
    say "Both are reified now!";
    say $seq[^2];

    # OUTPUT:
    # Let's reify an element!
    # About to make 1st element
    # 1
    # Let's reify more!
    # About to make 2nd element
    # 2
    # Both are reified now!
    # (1 2)

Following the output above, you can see the print statements I<inside> the
C<gather> got printed only when we reified the individual elements while looking
up an element. Also note, the elements got reified just once. When we printed
the same elements again on the last line of the example, the messages inside
C<gather> we no longer printed. This is because the construct used
already-reified elements from the L<Seq>'s cache.

Note that above we assigned the C<gather> to a L<Scalar> container (the C<$>
sigil), not the L<Positional> one (the C<@> sigil). The reason is that the
C<@>-sigiled variables are I<mostly lazy>. What this means is they
I<reify the stuff assigned to them> right away I<most of the time>. The only
time they don't do it is when the items are known to be
L«C<is-lazy>|/routine/is-lazy», like our sequence generated with infinity as the
end point. Were we to assign the C<gather> to a C<@>-variable, the C<say>
statements inside of it would've been printed right away.

Another way to fully-reify a list, is by calling L«C<.elems>|/routine/elems» on
it. This is the reason why checking whether a list contains any items is best
done by using C<.Bool> method (or just using C<if @array { … }>), since you don't
need to reify I<all> the elements to find out if there are C<any> of them.

There are times where you I<do> want to fully-reify a list before doing something.
For example, the L«C<IO::Handle.lines>|/type/IO::Handle#method_lines» returns
a L<Seq>. The following code contains a bug; keeping reification in mind, try to
spot it:

=for code
    my $fh = "/tmp/bar".IO.open;
    my $lines = $fh.lines;
    close $fh;
    say $lines[0];

We open a L<file handle|/type/IO::Handle>, then assign return of
L«C<.lines>|/type/IO::Handle#method_lines» to a L<Scalar> variable, so the
returned L<Seq> does not get reified right away. We then
L«C<close>|/routine/close» the file handle, and try to print an element from
C<$lines>.

The bug in the code is by the time we reify the C<$lines> L<Seq> on the last
line, we've I<already closed> the file handle. When the C<Seq's> iterator tries
to generate the item we've requested, it results in the error about attempting
to read from a closed handle. So, to fix the bug we can either assign to
a C<@>-sigiled variable or call L«C<.elems>|/routine/elems» on C<$lines> before
closing the handle:

=for code
    my $fh = "/tmp/bar".IO.open;
    my @lines = $fh.lines;
    close $fh;
    say @lines[0]; # no problem!

Also good:

=for code
    my $fh = "/tmp/bar".IO.open;
    my $lines = $fh.lines;
    say "Read $lines.elems() lines"; #reifying before closing handle
    close $fh;
    say $lines[0]; # no problem!

=head1 Repository
X<|Repository>

A filesystem under control of a source control management application, usually git,
that holds the sources for a project, library or application. This file, for
instance, is in L<a GitHub repository|https://github.com/perl6/doc>. Repositories store not only
files, but also history of changes and can be used by the developing
or writing team for interaction through issues or comments to code.

=head1 roast
X<|roast>

The Perl 6 L<specification tests|#test suite>, which live here:
L<https://github.com/perl6/roast/>.  Originally developed for L<#pugs>, it
now serves all Perl 6 implementations.  Why roast? It's the B<r>epository
B<o>f B<a>ll B<s>pec B<t>ests.

=head1 Roles
X<|role>

Roles, mix-ins or traits define interfaces and/or implementation of
those interfaces as well as instance variables using them, and are
mixed-in when declaring classes that follow that interface. L<Abstract
classes|#Abstract Class> are particular examples of Roles where the
actual implementation is deferred to the class that uses that Role.

Roles are part of Perl6's L<object system|/language/objects>, and are
declared using the keyword L<role|/syntax/role> and used in class
declaration via L<does|/syntax/does>.

=head1 rule
X<|rule>

(Used in regular expressions)

=head1 rvalue
X<|rvalue>

A value that can be used on the right hand side of an assignment.  See also
L<#lvalue>.

=head1 Sigil
X<|Sigil>

In Perl, the sigil is the first character of a variable name.  It must be
either $, @, %, or & respectively for a L<scalar|/type/Scalar>,
L<array|/type/Array>, L<hash|/type/Hash>, or L<code|/type/Code> variable.  See also
Twigil and role.  Also sigiled variables allow short conventions
for L<variable interpolation|#Variable Interpolation> in a double quoted
string, or even postcircumfix expressions starting with
such a variable.

=head1 Sigilless Variable
X<|Sigilless Variable>

=head1 Spesh
X<|Spesh>

A functionality of the L<#MoarVM> platform that uses run-time gathered data
to improve commonly used pieces of L<#bytecode>. It is much like a JIT
compiler, except that those usually output machine code rather than
bytecode.

=head1 STD
X<|STD>

STD.pm is the "standard" Perl 6 grammar definition, see
L<https://github.com/perl6/std/> that was used to implement Perl 6.
STD.pm is no longer really a "specification" in a proscriptive sense:
it's more of a guideline or model for Perl 6 implementations to follow.

=head1 Stub
X<|Stub>

=head1 Symbol
X<|Symbol>

Fancy alternative way to denote a name. Generally used in the context of
L<module|/language/modules>s linking, be it in the OS level, or at the Perl 6 L<#Virtual Machine> level
for modules generated from languages targeting these VMs.  The set of
imported or exported symbols is called the symbol table.

=head1 Synopsis
X<|Synopsis>

The current human-readable description of the Perl 6 language.  Still in
development.  Much more a community effort than the L<Apocalypses|#Apocalypse>
and L<Exegeses|#Exegesis> were. The current state of the language is reflected
by L<#roast>, its L<#test suite>, not the synopses where speculative material
is not always so flagged or more recent additions have not been documented.
This is even more true of material that has not been yet implemented.

=head1 Syntax Analysis
X<|Syntax Analysis>

=head1 test suite
X<|test suite>

The Perl 6 test suite is L<#roast>

=head1 ASCII operator
X<|ASCII operator>
X<|Texas operator>
=begin comment
“Texas” was used in the past but is now discouraged.
Remove the link when “Texas” goes completely out of use.
=end comment

The ASCII variant of a non-ASCII Unicode L<operator|#Operator> or
L<symbol|#Symbol>.
For instance, C<(elem)> corresponds to the C<∈> ("Is this an element of
that set?") operator that comes from set theory.  ASCII operators are a
workaround to the problem that people don't know how to type Unicode yet.
Culturally, while we encourage people to use the Unicode symbols in a
vague sort of way, we do not disparage the use of the
L<ASCII variants|/language/unicode_ascii>.
Well, maybe just a little...

=head1 TheDamian

L<#IRC> screen name for L<#Damian Conway>, writer of the original
L<Exegeses|#Exegesis>.

=head1 TimToady

L<#IRC> screen name for L<#Larry Wall>, creator of Perl. The name comes from
the pronunciation of L<#TIMTOWTDI> as a word.

=head1 Thunk
X<|Thunk>

A piece of code that isn't immediately executed, but doesn't have an independent scope.

=head1 twine
X<|twine>

A data structure used to hold a POD string with embedded formatting codes.  For example:

=begin code
=begin pod
C<foo>
=end pod
say $=pod[0].contents[0].contents.perl;
=end code

The output will be:

=begin code
["", Pod::FormattingCode.new(type => "C", meta => [], config => {}, contents => ["foo"]),""]
=end code

Note the C<twine> is an array with an odd number of elements beginning with a simple
string, alternating with formatting code objects and simple strings, and ending with
a simple string.  (The formatting code objects are interC<twine>d with the
strings.) The strings may be empty (as shown in the example).
A twine with no formatting code will contain one simple string.

=head1 value
X<|value>

=head1 Value type
X<|Value type>

A type is known as a B<value type> if it is immutable and any instance of that type is interchangeable with any other instance "of the same value"—that is, any instance constructed in the same way. An instance of a value type is often I<called> a B<value> (but should not be confused with L<#lvalue>s or L<#rvalue>s).

For example, numbers are value types, so a number constructed one place in your program with, for instance, the literal C<3> can't be changed in any way—it simply I<is> 3—and any later use of the literal C<3> can safely be pointed at the same place in memory as the first with no ill consequences.

Classes doing the roles L<Numeric|/type/Numeric> and L<Stringy|/type/Stringy> are among a few examples of built-in value types.

A value type is created by ensuring that an instance of the value type is immutable (i.e., its attributes cannot be modified after construction) and that its L«C<WHICH>|/routine/WHICH» method returns the same thing every time an instance with the same value is constructed (and conversely returns a different thing every time an instance with a different value is constructed).

The language is free to optimize based on the assumption that equivalent instances of value types are interchangeable, but you should not depend on any such optimization. For instance, if you want L«C<clone>|/routine/clone» to return an instance of C<self>, or you want instance construction to be memoized so that re-construction of a previously-constructed value always returns the same instance, you currently must override this behavior yourself.

(The same would hold true of object finalization, but if your instances need special destruction behavior, you almost certainly do not actually have a value type. Values should be thought of as "timeless" and existing in some ideal form outside of your program's memory, like natural values are.)

=head1 Variable
X<|Variable>

A variable is a name for a L<container|/language/containers>.

=head1 Variable Interpolation
X<|Variable Interpolation>

=head1 Virtual Machine
X<|Virtual Machine>

A virtual machine is the Perl compiler entity that executes the
L<bytecode|#bytecode>.  It can optimize the bytecode or generate
machine code Just in Time.  Examples are
L<#MoarVM>, L<#Parrot> (who are intended to run Perl 6) and more
generic virtual machines such as JVM and Javascript.

=head1 whitespace
X<|whitespace>

=head1 6model
X<|6model>

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
